{
  * Class to implement debug functionality on target platform.
  * Actually nothing but Windows is expected though such structuring is good
  * thing anyway.
}
unit vdbg.dbgapi;

{$mode delphi}

interface

uses
  vdbg.common;

type

  { TVDbgApi }

  TVDbgApi = class
  protected
    // Debuggee file name set on process creation/attach.
    FDebuggeeFileName: string;

    // Current event obtained after WaitForDebugEvent.
    FEvent: TVDbgEvent;

    // File name of loaded module after dbgevt_module_load event. Can be empty.
    FLoadedModuleFilename: string;

    // Output string after dbgevt_output_string event.
    FDebugOutputString: string;
  public
    constructor Create; virtual;

    // Create process for debugging.
    // Process must be paused and ready for debug event queries.
    function CreateProcess(
      const FileName: string;
      const Arguments: string
      ): boolean; virtual; abstract;

    // Attach to process for debugging.
    // Process must be paused and ready for debug event queries.
    function AttachToProcess(
      PID: TVDbgProcessId
      ): boolean; virtual; abstract;

    function Detach: boolean; virtual; abstract;

    // Terminate process created with CreateProcess. If it was not created
    // do nothing.
    function TerminateProcess(
      ): boolean; virtual; abstract;

    // Wait for any debug event to happen in TimeOut milliseconds. If there is
    // event result must be True and Event structure filled with event info.
    // On timeout result must be false. Timeout -1 is Infinite.
    // If fatal error happened and WaitForDebugEvent cannot be called anymore
    // result must be True and Event type must be dbgevt_die.
    // First event must be dbgevt_process_create, last event must be either
    // dbgevt_process_exit or dbgevt_die.
    function WaitForDebugEvent(
      TimeOut: integer
      ): boolean; virtual; abstract;

    // Continue process execution after WaitForDebugEvent. If there is no more
    // events waiting it means to resume process. Otherwise current event is
    // removed from queue and process stays paused.
    // If Handled is True process must continue as if there were no exception.
    // Otherwise debuggee must use its own exception handler.
    function ContinueEvent(
      ThreadId: TVDbgThreadId;
      Handled: boolean
      ): boolean; virtual; abstract;

    // http://msdn.microsoft.com/en-us/library/windows/desktop/ms679298(v=vs.85).aspx
    // Causes a breakpoint exception to occur in debuggee.
    // This allows to signal the debugger to handle the exception.
    function DebugBreak: boolean; virtual; abstract;

    // Read process memory.
    // Result is number of bytes read.
    function ReadMem(
      Addr: TVDbgAddr;
      Buf: Pointer;
      Size: Integer
      ): Integer; virtual; abstract;

    // Write process memory.
    // Result is number of bytes written.
    function WriteMem(
      Addr: TVDbgAddr;
      Buf: Pointer;
      Size: Integer
      ): Integer; virtual; abstract;

    // Get context of thread for current debug event.
    // Returned point to context must be already properly aligned.
    // It's allocated internally by this class.
    function GetThreadContext: PVDbgThreadContext; virtual; abstract;

    // Set context of thread for current debug event.
    function SetThreadContext(pCtx: PVDbgThreadContext): boolean; virtual; abstract;

    function SetBreakpoint(
      const Info: TVDbgBreakpointInfo
      ): Boolean; virtual; abstract;

    // Remove breakpoint by address. Restore patched bytes in process memory.
    function DelBreakpoint(
      const Addr: TVDbgAddr
      ): Boolean; virtual; abstract;

    property DebuggeeFileName: string read FDebuggeeFileName;
    property Event: TVDbgEvent read FEvent;
    property LoadedModuleFilename: string read FLoadedModuleFilename;
    property DebugOutputString: string read FDebugOutputString;
  end;

  TVDbgApiClass = class of TVDbgApi;

implementation

{ TVDbgApi }

constructor TVDbgApi.Create;
begin
  inherited Create;
end;

end.
